Description
Overview
Included files
Included by
Source
/** \dir
!!! Documenting
This page decribes the basics and concepts of DoxyS.\n
DoxyS is primarily a C++/C documentation tool and secondly a tool for making general
online documentation of any kind.
! For the impatient
If you just want to see what DoxyS can do to your code just run the $doxys$ executable
from the root of your code directory, or perhaps a subdirectory if You have a large
code base. DoxyS will make a default DoxySFile (configuration file) and use it. If
You want to learn how to document classes functions etc. please go to "Documenting the code"
or to HowToDocument example code.
!! Introduction
The basic idea is to reuse the the directory }structure} (hence the S in DoxyS)
in the generated output. Each subdirectory }should} have a directory file
documenting the contents in general terms giving the reader an introduction and basic
idea of how to use the code. The directory documentation files were invented because
we found that it often was the first kind of information we would like when trying
to familiarize ourselves with a new code library, but that no documentation tools
offered a logical place to put this documentation.\n
For this directory structure approach to work optimally we advise organizing Your
code in directories and subdirectories each containing only classes, functions etc.
that belongs together. Directories should then have a $.dir$ file which explains
the intent of the code found there.
!! Basics
The basic entities in the DoxyS documentation are Directories, Classes, Units and
Pages. These entities together form the navigation menu, which you find to the left
of all DoxyS generated documentation pages. So when You are navigating the documentation
You are also navigating the code!
Units serve as a way to document realated free functions as a group assuming that
free functions declared in the same header file do have something in common. In most
cases You probably don't need units, but when You do they come in quite handy.
Pages on the other hand serve as the perfect place to put any kind of code related
documentation. For example code related documentation that does not really fit
into the directory description file (see also dirCmd). Pages and directories together
can also be used together without any code inside the directories to form general
documentation or design documents.
!! Documentation blocks
In order for DoxyS to reconize a block of text as something that contains documentation
one should enclose the text in $/** .. \endds_doc$, or see the following table for all
the ways to designate a documentation block.
| #%Documentation Style# | #Syntax to use#
| Multi line || $/** \n... text block ... \n \endds_doc$
| C++ single line style ||$/// ... lines are ... \n/// ... concatenated to ... \n/// ... one single block ... \n$
| Multi line #'!'# || $/*! \n... text block ... \n \endds_doc$
| C++ single line style #'!'# ||$//! ... lines are ... \n//! ... concatenated to ... \n//! ... one single block ... \n$
*/